import { Code, InlineCode } from '~/components/text/code'
import { HelpLink } from '~/components/text/link'
import Note from '~/components/text/note'
import { P } from '~/components/text'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'
import Example from '~/components/example'

export const meta = {
  editUrl: 'pages/docs/api/v2/api-docs-mdx/endpoints/projects.mdx',
  lastEdited: '2019-10-28T15:35:28.000Z'
}

## Projects

### Create a Project

<Endpoint method="POST" url="/v1/projects/" />

Create a new project with the `name` request parameter. If the project already exists, fails with `409` status code.

#### Request Parameters

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                       |
| -------- | ---------------------------------------------------------- | -------- | --------------------------------- |
| **name** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The desired name for the project. |

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v1/projects/"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{ name: 'a-project-name' }}
/>

##### Example Response

<Code lang="json">{`{
  "id":"QmQKrt94KYKF3sDysJq19N87uMmE8Wicbt2GirePy1dH8U",
  "name":"a-project-name",
  "alias":[
    {
      "domain": "a-project-name-elegant-deer.now.sh",
      "target": "PRODUCTION",
      "createdAt": 1555413045188,
      "configuredBy": "A",
      "configuredChangedAt": 1555413045188
    }
  ],
  "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
  "updatedAt":1555413045188,
  "createdAt":1555413045188
}`}</Code>

### Ensure a Project Exists

<Endpoint method="POST" url="/v1/projects/ensure-project" />

Create a project with the `name` request parameter if it does not already exist. Updates the project `updatedAt` if it already exists.

#### Request Parameters

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                       |
| -------- | ---------------------------------------------------------- | -------- | --------------------------------- |
| **name** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The desired name for the project. |

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v1/projects/ensure-project"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    name: 'a-project-name'
  }}
/>

##### Example Response

<Code lang="json">{`{
  "id":"QmQKrt94KYKF3sDysJq19N87uMmE8Wicbt2GirePy1dH8U",
  "name":"a-project-name",
  "alias":[
    {
      "domain": "a-project-name-elegant-deer.now.sh",
      "target": "PRODUCTION",
      "createdAt": 1555413045188,
      "configuredBy": "A",
      "configuredChangedAt": 1555413045188
    }
  ],
  "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
  "updatedAt":1555413045188,
  "createdAt":1555413045188
}`}</Code>

### Get All Projects

<Endpoint method="GET" url="/v2/projects/" />

Get a list of all the projects you currently have under your account.

<Note>
  The order is always based on the <InlineCode>updatedAt</InlineCode> field of
  the project.
</Note>

#### Query Parameters

| Key        | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                                        |
| ---------- | ---------------------------------------------------------- | -------- | -------------------------------------------------- |
| **limit**  | <HelpLink href="#api-basics/types">Number</HelpLink>       | No       | Limit the number of projects returned.             |
| **from**   | <HelpLink href="#api-basics/types">Date</HelpLink>         | No       | The `updatedAt` point where the list should start. |
| **search** | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | Search projects by the name field.                 |

##### Example Request

<Request url="https://api.zeit.co/v2/projects/?limit=2" auth />

##### Example Response

<Code lang="json">{`
[
  {
    "id":"QmQKrt94KYKF3sDysJq19N8gvhmE8Wicbt2GirePy1dH8U",
    "name":"a-project-name",
    "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
    "createdAt":1555413045188,
    "updatedAt":1555413045188,
    "targets": {},
    "latestDeployments": []
  },
  {
    "id":"QmRhxc9HAmRMcLvWhCAf2ALLctxZ4s4fwsM1D5kNM8PJuL",
    "name":"another-project-name",
    "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
    "createdAt":1555072968396,
    "updatedAt":1555345633993,
    "targets": {},
    "latestDeployments": []
  }
]
`}</Code>

### Get a Single Project

<Endpoint>
  GET /v1/projects/:id
  <br />
  GET /v1/projects/:name
</Endpoint>

Get the information for a specific project by passing either the project `id` or `name` in the URL.

#### URL Parameters

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| -------- | ---------------------------------------------------------- | -------- | ------------------------------ |
| **id**   | <HelpLink href="#api-basics/types">ID</HelpLink>           | No       | The unique project identifier. |
| **name** | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | The project name.              |

#### Response Parameters

| Key                   | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                                                                           |
| --------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **id**                | <HelpLink href="#api-basics/types">ID</HelpLink>           | A string holding the unique ID of the project.                                                                        |
| **name**              | <HelpLink href="#api-basics/types">String</HelpLink>       | The name of the project.                                                                                              |
| **alias**             | <HelpLink href="#api-basics/types">List</HelpLink>         | A list of production domains for the project.                                                                         |
| **accountId**         | <HelpLink href="#api-basics/types">String</HelpLink>       | The unique ID of the user or team the project belongs to.                                                             |
| **createdAt**         | <HelpLink href="#api-basics/types">Date</HelpLink>         | A number containing the date when the project was created in milliseconds.                                            |
| **updatedAt**         | <HelpLink href="#api-basics/types">Date</HelpLink>         | A number containing the date when the project was updated in milliseconds.                                            |
| **env**               | <HelpLink href="#api-basics/types">List</HelpLink>         | A list of environment variables configured for the project.                                                           |
| **targets**           | <HelpLink href="#api-basics/types">Map</HelpLink>          | An object which has a `production` key containing the production deployment object, if a production deployment exists |
| **latestDeployments** | <HelpLink href="#api-basics/types">List</HelpLink>         | A list of the latest deployments for the project                                                                      |

##### Example Request

<Request url="https://api.zeit.co/v1/projects/a-project-name" auth />

##### Example Response

<Code lang="json">{`{
  "id":"QmQKrt94KYKF3sDysJq19N8gvhmE8Wicbt2GirePy1dH8U",
  "name":"a-project-name",
  "alias": [
    {
      "createdAt": 1555413045188,
      "domain": "foobar.com",
      "target": "PRODUCTION",
      "configuredBy": "A",
      "configuredChangedAt": 1555413045188
    }
  ],
  "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
  "createdAt":1555413045188,
  "updatedAt":1555413045188,
  "env": [
    {
      "key": "API_SECRET",
      "value": "@a-new-secret",
      "configurationId": null,
      "updatedAt": 1557241361455,
      "createdAt": 1557241361455
    }
  ],
  "targets": {
    "production": {
      "alias": [
        "foobar.com"
      ],
      "aliasAssigned": 1571239348998,
      "createdAt": 1571239348998,
      "createdIn": "sfo1",
      "deploymentHostname": "a-project-name-rjtr4pz3f",
      "forced": false,
      "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
      "meta": {},
      "plan": "pro",
      "private": true,
      "readyState": "READY",
      "requestedAt": 1571239348998,
      "target": "production",
      "teamId": null,
      "type": "LAMBDAS",
      "url": "a-project-name-rjtr4pz3f.now.sh",
      "userId": "K4amb7K9dAt5R2vBJWF32bmY"
    }
  },
  "latestDeployments": [
    {
      "alias": [
        "foobar.com"
      ],
      "aliasAssigned": 1571239348998,
      "createdAt": 1571239348998,
      "createdIn": "sfo1",
      "deploymentHostname": "a-project-name-rjtr4pz3f",
      "forced": false,
      "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
      "meta": {},
      "plan": "pro",
      "private": true,
      "readyState": "READY",
      "requestedAt": 1571239348998,
      "target": "production",
      "teamId": null,
      "type": "LAMBDAS",
      "url": "a-project-name-rjtr4pz3f.now.sh",
      "userId": "K4amb7K9dAt5R2vBJWF32bmY"
    }
  ]
}`}</Code>

### Update a Single Project

<Endpoint>
  PATCH /v2/projects/:id
  <br />
  PATCH /v2/projects/:name
</Endpoint>

Update the fields of a project using either its `name` or `id`.

#### Request Parameters

| Key                 | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                                                                                                                           |
| ------------------- | ---------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **framework**       | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | The framework that is being used for this project. When `null` is used no framework is selected.                                          |
| **publicSource**    | <HelpLink href="#api-basics/types">Boolean</HelpLink>      | No       | Specifies whether the source code and logs of the deployments for this project should be public or not.                                |
| **buildCommand**    | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | The build command for this project. When `null` is used this value will be automatically detected.                                    |
| **devCommand**      | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | The dev command for this project. When `null` is used this value will be automatically detected.                                      |
| **outputDirectory** | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | The output directory of the project. When `null` is used this value will be automatically detected.                                   |
| **rootDirectory**   | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | The name of a directory or relative path to the source code of your project. When `null` is used it will default to the project root. |

##### Example Request

<Request
  method="PATCH"
  url="https://api.zeit.co/v2/projects/a-project-name"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    framework: 'nextjs',
    publicSource: false,
    buildCommand: 'yarn run different-build',
    devCommand: 'yarn run different-dev',
    outputDirectory: null
  }}
/>

##### Example Response

<Code lang="json">{`{
  "id": "QmQKrt94KYKF3sDysJq19N87uMmE8Wicbt2GirePy1dH8U",
  "name": "a-project-name",
  "accountId": "K4amb7K9dAt5R2vBJWF32bmY",
  "framework": 'nextjs',
  "publicSource": false,
  "buildCommand": "yarn run different-build",
  "devCommand": "yarn run different-dev",
  "outputDirectory": null,
  "updatedAt": 1555413045188,
  "createdAt": 1575972468641
}`}</Code>

### Remove a Single Project

<Endpoint>
  DELETE /v1/projects/:id
  <br />
  DELETE /v1/projects/:name
</Endpoint>

Delete a specific project by passing either the project `id` or `name` in the URL.

#### URL Parameters

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| -------- | ---------------------------------------------------------- | -------- | ------------------------------ |
| **id**   | <HelpLink href="#api-basics/types">ID</HelpLink>           | No       | The unique project identifier. |
| **name** | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | The project name.              |

##### Example Request

<Request
  method="DELETE"
  url="https://api.zeit.co/v1/projects/a-project-name"
  auth
/>

<Note>
  If the request is successful, you will receive a 204 HTTP Status code in the
  response.
</Note>

### Get Project Environment Variables

<Endpoint method="GET" url="/v1/projects/:id/env" />

Retrieve the environment variables for a given project by passing the project `id` in the URL.

#### URL Parameters

| Key    | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| ------ | ---------------------------------------------------------- | -------- | ------------------------------ |
| **id** | <HelpLink href="#api-basics/types">ID</HelpLink>           | Yes      | The unique project identifier. |

##### Example Request

<Request
  url="https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env"
  auth
/>

##### Example Response

<Code lang="json">{`[
  {
    "key": "API_SECRET",
    "value": "@a-new-secret",
    "configurationId": null,
    "updatedAt": 1557241361455,
    "createdAt": 1557241361455
  }
]`}</Code>

### Create a Project Environment Variable

<Endpoint method="POST" url="/v1/projects/:id/env" />

Create a new environment variable for the project by passing the project `id` in the URL and a `key` and `value` as request parameters.

<Note>
  For security, only secrets can be used for these environment variables.
</Note>

<Note>
  Only deployments made after this call will receive the environment variables
  set.
</Note>

#### URL Parameters

| Key    | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| ------ | ---------------------------------------------------------- | -------- | ------------------------------ |
| **id** | <HelpLink href="#api-basics/types">ID</HelpLink>           | Yes      | The unique project identifier. |

#### Request Parameters

| Key       | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                            |
| --------- | ---------------------------------------------------------- | -------- | -------------------------------------- |
| **key**   | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The name of the environment variable.  |
| **value** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The value of the environment variable. |

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    key: 'API_SECRET',
    value: '@a-new-secret'
  }}
/>

##### Example Response

<Code lang="json">{`[
  {
    "key": "API_SECRET",
    "value": "@a-new-secret",
    "configurationId": null,
    "updatedAt": 1557241361455,
    "createdAt": 1557241361455
  }
]`}</Code>

<Note>
  The response will include all environment variables for the project.
</Note>

<Note>
  The <InlineCode>configurationId</InlineCode> depends on the token used to make
  the request.
</Note>

### Delete a Specific Environment Variable

<Endpoint method="DELETE" url="/v1/projects/:id/env/:key" />

Delete a specific environment variable for a given project by passing both the project `id` and `env` key in the URL.

#### URL Parameters

| Key     | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| ------- | ---------------------------------------------------------- | -------- | ------------------------------ |
| **id**  | <HelpLink href="#api-basics/types">ID</HelpLink>           | Yes      | The unique project identifier. |
| **key** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The environment variable key.  |

##### Example Request

<Request
  method="DELETE"
  url="https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env/API_SECRET"
  auth
/>

##### Example Response

<Code lang="json">{`[]`}</Code>

<Note>
  The response will include all <b>remaining</b> environment variables for the
  project.
</Note>

### Add a Domain to a Project

<Endpoint method="POST" url="/v1/projects/:id/alias" />

Add a domain to the project by passing the project `id` in the URL and the `domain` and `redirect` as request parameters. If the domain already exists on the project, fails with `400` status code.

#### URL Parameters

| Key    | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| ------ | ---------------------------------------------------------- | -------- | ------------------------------ |
| **id** | <HelpLink href="#api-basics/types">ID</HelpLink>           | Yes      | The unique project identifier. |

#### Request Parameters

| Key          | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                            |
| ------------ | ---------------------------------------------------------- | -------- | -------------------------------------- |
| **domain**   | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The name of the production domain.     |
| **redirect** | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | Target destination domain for redirect |

<Note>You can only redirect to domains that belong to the project.</Note>

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/alias"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    domain: 'foobar.com',
    redirect: null
  }}
/>

##### Example Response (successful)

<Code lang="json">{`[
  {
    "createdAt": 1562119110860,
    "domain": "foobar.com",
    "target": "PRODUCTION",
    "configuredBy": "A",
    "configuredChangedAt": 1562119110860
  }
]`}</Code>

##### Example response (unsuccessful)

<Code lang="json">{`{
  "error": {
    "code": "ALIAS_DOMAIN_EXIST",
    "domain": "foobar.com",
    "project": {
      "id": "QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF",
      "name": "a-project-name",
      "accountId": "K4amb7K9dAt5R2vBJWF32bmY",
    }
  }
}`}</Code>

<Note>
  The response will include all production domains configured for the project.
</Note>

<Note>
  You can also get the production domains from the{' '}
  <InlineCode>alias</InlineCode> field of a project, returned by any other
  project API endpoints.
</Note>

### Set Redirect for a Domain

<Endpoint method="PATCH" url="/v1/projects/:id/alias" />

Set redirect from specified domain to a different domain in the same project (status code 307).

#### URL Parameters

| Key    | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| ------ | ---------------------------------------------------------- | -------- | ------------------------------ |
| **id** | <HelpLink href="#api-basics/types">ID</HelpLink>           | Yes      | The unique project identifier. |

#### Request Parameters

| Key          | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                             |
| ------------ | ---------------------------------------------------------- | -------- | --------------------------------------- |
| **domain**   | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The name of the production domain.      |
| **redirect** | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | Target destination domain for redirect. |

<Note>You can only redirect to domains that belong to the project.</Note>

##### Example Request

<Request
  method="PATCH"
  url="https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/alias"
  auth
  body={{
    domain: 'www.foobar.com',
    redirect: 'foobar.com'
  }}
/>

##### Example response:

<Code lang="json">{`[
  {
    "createdAt": 1571138625066,
    "domain": "foobar.com",
    "target": "PRODUCTION",
    "configuredBy": "A",
    "configuredChangedAt": 1571945629322
  },
  {
    "createdAt": 1571921061602,
    "domain": "www.foobar.com",
    "target": "PRODUCTION",
    "redirect": "foobar.com",
    "configuredBy": "CNAME",
    "configuredChangedAt": 1571945629501
  }
]`}</Code>

<Note>
  The response will include all production domains configured for the project.
</Note>

<Note>
  You can also retrieve the production domains from the{' '}
  <InlineCode>alias</InlineCode> field of a project, returned by any other
  project API endpoints.
</Note>

### Delete a Specific Production Domain of a Project

<Endpoint method="DELETE" url="/v1/projects/:id/alias?domain" />

Delete a specific production domain configuration from a project by passing the project `id` and a `domain` query in the URL.

<Note>
  After deleting the domain, all remaining aliases and deployments will not be
  affected.
</Note>

#### URL Parameters

| Key    | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| ------ | ---------------------------------------------------------- | -------- | ------------------------------ |
| **id** | <HelpLink href="#api-basics/types">ID</HelpLink>           | Yes      | The unique project identifier. |

#### Query Parameters

| Key        | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                        |
| ---------- | ---------------------------------------------------------- | -------- | ---------------------------------- |
| **domain** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The name of the production domain. |

##### Example Request

<Request
  method="DELETE"
  url="https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/alias?domain=foobar.com"
  auth
/>

##### Example Response

<Code lang="json">{`[]`}</Code>

<Note>
  The response will include all the remaining production domains configured for
  the project.
</Note>
